/*
 * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//httpclient/src/java/org/apache/commons/httpclient/methods/ExpectContinueMethod.java,v 1.13 2004/05/08 10:12:08 olegk Exp $
 * $Revision: 480424 $
 * $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 2006) $
 *
 * ====================================================================
 *
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of the Apache Software Foundation.  For more
 * information on the Apache Software Foundation, please see
 * <http://www.apache.org/>.
 *
 */

package org.apache.commons.httpclient.methods;

import java.io.IOException;
import org.apache.commons.httpclient.HttpConnection;
import org.apache.commons.httpclient.HttpException;
import org.apache.commons.httpclient.HttpMethodBase;
import org.apache.commons.httpclient.HttpState;
import org.apache.commons.httpclient.HttpVersion;
import org.apache.commons.httpclient.params.HttpMethodParams;
import org.apache.commons.logging.Log;

/**
 * <p>
 * This abstract class serves as a foundation for all HTTP methods that support
 * 'Expect: 100-continue' handshake.
 * </p>
 * 
 * <p>
 * The purpose of the 100 (Continue) status (refer to section 10.1.1 of the RFC
 * 2616 for more details) is to allow a client that is sending a request message
 * with a request body to determine if the origin server is willing to accept
 * the request (based on the request headers) before the client sends the
 * request body. In some cases, it might either be inappropriate or highly
 * inefficient for the client to send the body if the server will reject the
 * message without looking at the body.
 * </p>
 * 
 * <p>
 * 'Expect: 100-continue' handshake should be used with caution, as it may cause
 * problems with HTTP servers and proxies that do not support HTTP/1.1 protocol.
 * </p>
 * 
 * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
 * 
 * @since 2.0beta1
 */

public abstract class ExpectContinueMethod extends HttpMethodBase {

	/** LOG object for this class. */
	// private static final Log LOG =
	// LogFactory.getLog(ExpectContinueMethod.class);

	/**
	 * No-arg constructor.
	 * 
	 * @since 2.0
	 */
	public ExpectContinueMethod() {
		super();
	}

	/**
	 * Constructor specifying a URI.
	 * 
	 * @param uri
	 *            either an absolute or relative URI
	 * 
	 * @since 2.0
	 */
	public ExpectContinueMethod(String uri) {
		super(uri);
	}

	/**
	 * <p>
	 * Returns <tt>true</tt> if the 'Expect: 100-Continue' handshake is
	 * activated. The purpose of the 'Expect: 100-Continue' handshake to allow a
	 * client that is sending a request message with a request body to determine
	 * if the origin server is willing to accept the request (based on the
	 * request headers) before the client sends the request body.
	 * </p>
	 * 
	 * @return <tt>true</tt> if 'Expect: 100-Continue' handshake is to be used,
	 *         <tt>false</tt> otherwise.
	 * 
	 * @since 2.0beta1
	 * 
	 * @deprecated Use {@link HttpMethodParams}
	 * 
	 * @see #getParams()
	 * @see HttpMethodParams
	 * @see HttpMethodParams#USE_EXPECT_CONTINUE
	 */
	public boolean getUseExpectHeader() {
		return getParams().getBooleanParameter(
				HttpMethodParams.USE_EXPECT_CONTINUE, false);
	}

	/**
	 * <p>
	 * Activates 'Expect: 100-Continue' handshake. The purpose of the 'Expect:
	 * 100-Continue' handshake to allow a client that is sending a request
	 * message with a request body to determine if the origin server is willing
	 * to accept the request (based on the request headers) before the client
	 * sends the request body.
	 * </p>
	 * 
	 * <p>
	 * The use of the 'Expect: 100-continue' handshake can result in noticable
	 * peformance improvement for entity enclosing requests (such as POST and
	 * PUT) that require the target server's authentication.
	 * </p>
	 * 
	 * <p>
	 * 'Expect: 100-continue' handshake should be used with caution, as it may
	 * cause problems with HTTP servers and proxies that do not support HTTP/1.1
	 * protocol.
	 * </p>
	 * 
	 * @param value
	 *            boolean value
	 * 
	 * @since 2.0beta1
	 * 
	 * @deprecated Use {@link HttpMethodParams}
	 * 
	 * @see #getParams()
	 * @see HttpMethodParams
	 * @see HttpMethodParams#USE_EXPECT_CONTINUE
	 */
	public void setUseExpectHeader(boolean value) {
		getParams().setBooleanParameter(HttpMethodParams.USE_EXPECT_CONTINUE,
				value);
	}

	/**
	 * Returns <tt>true</tt> if there is a request body to be sent. 'Expect:
	 * 100-continue' handshake may not be used if request body is not present
	 * 
	 * @return boolean
	 * 
	 * @since 2.0beta1
	 */
	protected abstract boolean hasRequestContent();

	/**
	 * Sets the <tt>Expect</tt> header if it has not already been set, in
	 * addition to the "standard" set of headers.
	 * 
	 * @param state
	 *            the {@link HttpState state} information associated with this
	 *            method
	 * @param conn
	 *            the {@link HttpConnection connection} used to execute this
	 *            HTTP method
	 * 
	 * @throws IOException
	 *             if an I/O (transport) error occurs. Some transport exceptions
	 *             can be recovered from.
	 * @throws HttpException
	 *             if a protocol exception occurs. Usually protocol exceptions
	 *             cannot be recovered from.
	 */
	protected void addRequestHeaders(HttpState state, HttpConnection conn)
			throws IOException, HttpException {
		// LOG.trace("enter ExpectContinueMethod.addRequestHeaders(HttpState, HttpConnection)");

		super.addRequestHeaders(state, conn);
		// If the request is being retried, the header may already be present
		boolean headerPresent = (getRequestHeader("Expect") != null);
		// See if the expect header should be sent
		// = HTTP/1.1 or higher
		// = request body present

		if (getParams().isParameterTrue(HttpMethodParams.USE_EXPECT_CONTINUE)
				&& getEffectiveVersion().greaterEquals(HttpVersion.HTTP_1_1)
				&& hasRequestContent()) {
			if (!headerPresent) {
				setRequestHeader("Expect", "100-continue");
			}
		} else {
			if (headerPresent) {
				removeRequestHeader("Expect");
			}
		}
	}
}
